home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 July / EnigmA AMIGA RUN 20 (1997)(G.R. Edizioni)(IT)[!][issue 1997-07 & 08][EAR-CD IV].iso / earcd / mus / play / splibdev.lha / superplay-lib_DEV / Programmers / autodocs / SPObject_Ref_ENG.doc < prev    next >
Text File  |  1997-04-03  |  17KB  |  728 lines
  1. TABLE OF CONTENTS
  2.  
  3. SPObject.library/--background--
  4. SPObject.library/SPO_AllocHandle
  5. SPObject.library/SPO_FreeHandle
  6. SPObject.library/SPO_Read
  7. SPObject.library/SPO_StartReplay
  8. SPObject.library/SPO_Write
  9. SPObject.library/SPO_StopReplay
  10. SPObject.library/SPO_FreeResources
  11. SPObject.library/SPO_SetAccessMode
  12. SPObject.library/SPO_SetWriteSubType
  13. SPObject.library/SPO_SetWriteName
  14. SPObject.library/SPO_SetReadName
  15. SPObject.library/SPO_FileInfoRequest
  16. SPObject.library/SPO_CheckFileType
  17. SPObject.library/SPO_SetReqIOWindow
  18. SPObject.library/SPO_ContinueReplay
  19. SPObject.library/SPO_FastForward
  20. SPObject.library/SPO_FastBackward
  21. SPObject.library/SPO_GetSampleBuffer
  22. SPObject.library/SPO_GetSampleInfo
  23. SPObject.library/SPO_GetSampleList
  24. SPObject.library/SPO_SetSampleList
  25.  
  26.  SPObject.library/--background--
  27.  
  28.    VERSION
  29.         $VER: SPObject_Ref_ENG.doc V6.3 (3.4.97)
  30.  
  31.    COPYRIGHT
  32.         © 1995-97 by Andreas R. Kleinert. All rights reserved.
  33.  
  34.         - Feel free to translate this Doc-File into other languages. -
  35.  
  36.    GENERAL
  37.           Andreas R. Kleinert,
  38.           Sandstrasse 1,
  39.           D-57072 Siegen,
  40.           Germany.
  41.  
  42.         EMail:  Fido             Andreas Kleinert 2:2457/350.18
  43.                 Usenet/InterNet  Andreas_Kleinert@superview.ftn.neckar-alb.de
  44.  
  45.           If nothing else works, try one of these Fido-InterNet gateways:
  46.  
  47.                 Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
  48.                 Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)
  49.  
  50.    NOTE
  51.         * DO _NEVER_ ACCESS ANY SPOBJECTS DIRECTLY.
  52.         * DO NEVER BYPASS superplay.library !
  53.  
  54.         THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SPOBJECTS :
  55.  
  56.  
  57.    HISTORY
  58.         V2.5   Autodoc format
  59.                Change one SVO_ prefix to SPO_
  60.                Add version behind NAME
  61.                SPObject.library/SPO_SetReadeName
  62.                                          ^
  63.                  -> SPObject.library/SPO_SetReadName(indy)
  64.         V5.1   applied some more changes (ak)
  65.         V5.2   add "()" to function names in text for better autodocs
  66.                support(indy)
  67.         V6.3   bumped version
  68.                updated copyright note
  69.                updated email address list (ak)
  70.  
  71.  
  72.  SPObject.library/SPO_AllocHandle             SPObject.library/SPO_AllocHandle
  73.  
  74.    NAME
  75.         SPO_AllocHandle  (V1)
  76.  
  77.    SYNOPSIS
  78.  
  79.         APTR SPO_AllocHandle(APTR future)
  80.         D0   -$1e            A1
  81.  
  82.    FUNCTION
  83.  
  84.         Allocates a handle for accessing a Sample/Module via SPObjects.
  85.  
  86.    INPUT(S)
  87.  
  88.         future - always NULL yet
  89.  
  90.    RESULT
  91.  
  92.         A pointer to a new allocated Handle or NULL, if allocation failed.
  93.  
  94.    WARNING
  95.  
  96.         Test, if the result was NULL, or not !
  97.  
  98.    SEE ALSO
  99.  
  100.         SPO_FreeResources(), SPO_FreeHandle()
  101.  
  102.  SPObject.library/SPO_FreeHandle               SPObject.library/SPO_FreeHandle
  103.  
  104.    NAME
  105.         SPO_FreeHandle  (V1)
  106.  
  107.    SYNOPSIS
  108.  
  109.         VOID SPO_FreeHandle(APTR handle)
  110.         D0   -$24           A1
  111.  
  112.    FUNCTION
  113.  
  114.        Stops playing, frees all Resources and delocates a Handle, which has
  115.        been allocated with SPO_AllocHandle() before.
  116.  
  117.    INPUT(S)
  118.  
  119.         handle - a valid handle
  120.  
  121.    RESULT
  122.  
  123.         -
  124.  
  125.    SEE ALSO
  126.  
  127.         SPO_AllocHandle(), SPO_StopReplay(), SPO_FreeResources()
  128.  
  129.  SPObject.library/SPO_Read                           SPObject.library/SPO_Read
  130.  
  131.    NAME
  132.         SPO_Read  (V1)
  133.  
  134.    SYNOPSIS
  135.  
  136.         ULONG SPO_Read(APTR handle)
  137.         D0    -$2a     A1
  138.  
  139.    FUNCTION
  140.  
  141.         Loads the Sample/Module described by FileName, which then may
  142.         e.g. be replayed by SPO_StartReplay().
  143.  
  144.    INPUT(S)
  145.  
  146.         handle   - a valid handle
  147.  
  148.    RESULT
  149.  
  150.         NULL or an adequate SPERR-Errorcode.
  151.  
  152.    SEE ALSO
  153.  
  154.         SPO_AllocHandle(), SPO_StopReplay(), SPO_StartReplay(),
  155.         SPO_ContinueReplay(), SPO_FastForward(), SPO_FastBackward(),
  156.         SPO_FreeHandle()
  157.  
  158.  SPObject.library/SPO_StartReplay             SPObject.library/SPO_StartReplay
  159.  
  160.    NAME
  161.         SPO_StartReplay  (V1)
  162.  
  163.    SYNOPSIS
  164.  
  165.         ULONG SPO_StartReplay(APTR handle)
  166.         D0    -$30            A1
  167.  
  168.    FUNCTION
  169.  
  170.         Play the Sample/Module described by FileName, which has been loaded
  171.         via SPO_Read() before.
  172.  
  173.         Playing can be stopped either via full delocation of the handle
  174.         or temporal interruption with SPO_StopReplay().
  175.  
  176.    INPUT(S)
  177.  
  178.         handle   - a valid handle
  179.  
  180.    RESULT
  181.  
  182.         NULL or an adequate SPERR-Errorcode.
  183.  
  184.    SEE ALSO
  185.  
  186.         SPO_AllocHandle(), SPO_Read(), SPO_StopReplay(),
  187.         SPO_ContinueReplay(), SPO_FastForward(), SPO_FastBackward(),
  188.         SPO_FreeHandle()
  189.  
  190.  SPObject.library/SPO_Write                         SPObject.library/SPO_Write
  191.  
  192.    NAME
  193.         SPO_Write  (V1)
  194.  
  195.    SYNOPSIS
  196.  
  197.         ULONG SPO_Write(APTR handle, struct SPObjectBase *SourceBase,
  198.         D0    -$36      A1           A2
  199.  
  200.                         APTR source_handle)
  201.                         A3
  202.  
  203.    FUNCTION
  204.  
  205.         This functions allows to access an other SPObject, get the Sample-
  206.         Data from there (only works with SampleType-SPObjects) and
  207.         then writes this data in its own FileFormat.
  208.  
  209.         If "SourceBase" and "source_handle" are both NULL,
  210.         it is checked, whether a SampleList has been set via
  211.         "SPO_SetSampleList()", and then this SampleList is completely
  212.         saved.
  213.  
  214.    INPUT(S)
  215.  
  216.         handle        - a valid handle
  217.                         (used for Write Access)
  218.         SourceBase    - pointer to Base of other SPObject
  219.                         (may be NULL for V2+ SPObjects)
  220.         source_handle - handle for accessing the other SPObject
  221.                         (may be NULL for V2+ SPObjects)
  222.  
  223.    RESULT
  224.  
  225.         NULL or an adequate SPERR-Errorcode.
  226.  
  227.    SEE ALSO
  228.  
  229.         SPO_AllocHandle(), SPO_Read(), SPO_FreeHandle()
  230.  
  231.  SPObject.library/SPO_StopReplay               SPObject.library/SPO_StopReplay
  232.  
  233.    NAME
  234.         SPO_StopReplay  (V1)
  235.  
  236.    SYNOPSIS
  237.  
  238.         VOID SPO_StopReplay(APTR handle)
  239.         D0   -$3c           A1
  240.  
  241.    FUNCTION
  242.  
  243.         Stops playing the Sample/Module, indentified by the handle.
  244.         Some SPObjects support to continue the Sample/Module with
  245.         SPO_ContinueReplay() after calling SPO_StopReplay().
  246.  
  247.    INPUT(S)
  248.  
  249.         handle - a valid handle
  250.  
  251.    RESULT
  252.  
  253.         -
  254.  
  255.    SEE ALSO
  256.  
  257.         SPO_ContinueReplay(), SPO_FreeResources(), SPO_FreeHandle()
  258.  
  259.  SPObject.library/SPO_FreeResources         SPObject.library/SPO_FreeResources
  260.  
  261.    NAME
  262.         SPO_FreeResources  (V1)
  263.  
  264.    SYNOPSIS
  265.  
  266.         VOID SPO_FreeResources(APTR handle)
  267.         D0   -$42              A1
  268.  
  269.    FUNCTION
  270.  
  271.         Frees all resources belonging to the specific Sample/Module,
  272.         indentified by the handle, which are not needed to just replay it.
  273.         Playing of the Sample/Module is not stopped and/or interrupted.
  274.  
  275.    INPUT(S)
  276.  
  277.         handle - a valid handle
  278.  
  279.    RESULT
  280.  
  281.         -
  282.  
  283.    SEE ALSO
  284.  
  285.         SPO_AllocHandle(), SPO_StopReplay(), SPO_FreeHandle()
  286.  
  287.  SPObject.library/SPO_SetAccessMode         SPObject.library/SPO_SetAccessMode
  288.  
  289.    NAME
  290.         SPO_SetAccessMode  (V1)
  291.  
  292.    SYNOPSIS
  293.  
  294.         ULONG SPO_SetAccessMode(APTR handle, ULONG mode)
  295.         D0    -$48              A1           D1
  296.  
  297.    FUNCTION
  298.  
  299.         Initializes a Handle for ClipBoard or AmigaDOS access,
  300.         depending on the "mode" parameter.
  301.  
  302.    INPUT(S)
  303.  
  304.         handle - a valid handle
  305.         mode   - access mode value
  306.  
  307.  
  308.    RESULT
  309.  
  310.         NULL or an adequate SPERR-Errorcode.
  311.  
  312.    SEE ALSO
  313.  
  314.         -
  315.  
  316.  SPObject.library/SPO_SetWriteSubType     SPObject.library/SPO_SetWriteSubType
  317.  
  318.    NAME
  319.         SPO_SetWriteSubType  (V1)
  320.  
  321.    SYNOPSIS
  322.  
  323.         ULONG SPO_SetWriteSubType(APTR handle, ULONG write_type, APTR future)
  324.         D0    -$4e                A1           A2                A3
  325.  
  326.    FUNCTION
  327.  
  328.         Sets the write_type for a SPO_Write() call.
  329.         See description there and example SourceCodes for more and
  330.         detailed information.
  331.  
  332.    INPUT(S)
  333.  
  334.         handle     - a valid handle
  335.         write_type - a valid temporary write_type code form the SPObject List
  336.         future     - always NULL yet
  337.  
  338.  
  339.    RESULT
  340.  
  341.         NULL or an adequate SPERR-Errorcode.
  342.  
  343.    SEE ALSO
  344.  
  345.         SPO_Write()
  346.  
  347.  SPObject.library/SPO_SetWriteName           SPObject.library/SPO_SetWriteName
  348.  
  349.    NAME
  350.         SPO_SetWriteName  (V1)
  351.  
  352.    SYNOPSIS
  353.  
  354.         ULONG SPO_SetWriteName(APTR handle, UBYTE *write_name, APTR future)
  355.         D0    -$54             A1           A2                 A3
  356.  
  357.    FUNCTION
  358.  
  359.         Sets the write_name for a SPO_Write() call.
  360.         See description there and example SourceCodes for more and
  361.         detailed information.
  362.  
  363.    INPUT(S)
  364.  
  365.         handle     - a valid handle
  366.         write_name - a valid AmigaDOS FilePath and -Name description
  367.         future     - always NULL yet
  368.  
  369.  
  370.    RESULT
  371.  
  372.         NULL or an adequate SPERR-Errorcode.
  373.  
  374.    SEE ALSO
  375.  
  376.         SPO_Write()
  377.  
  378.  SPObject.library/SPO_SetReadName             SPObject.library/SPO_SetReadName
  379.  
  380.    NAME
  381.         SPO_SetReadName  (V1)
  382.  
  383.    SYNOPSIS
  384.  
  385.         ULONG SPO_SetReadName(APTR handle, ULONG reade_name, APTR future)
  386.         D0    -$5a            A1           A2                A3
  387.  
  388.    FUNCTION
  389.  
  390.         Sets the reade_name for a SPO_Read() call.
  391.         See description there and example SourceCodes for more and
  392.         detailed information.
  393.  
  394.    INPUT(S)
  395.  
  396.         handle     - a valid handle
  397.         write_name - a valid AmigaDOS FilePath and -Name description
  398.         future     - always NULL yet
  399.  
  400.  
  401.    RESULT
  402.  
  403.         NULL or an adequate SPERR-Errorcode.
  404.  
  405.    SEE ALSO
  406.  
  407.         SPO_Write()
  408.  
  409.  SPObject.library/SPO_FileInfoRequest     SPObject.library/SPO_FileInfoRequest
  410.  
  411.    NAME
  412.         SPO_FileInfoRequest  (V1)
  413.  
  414.    SYNOPSIS
  415.  
  416.         ULONG SPO_FileInfoRequest(APTR handle, struct Window *window,
  417.         D0    -$60                A1           A2
  418.  
  419.                                   APTR future)
  420.                                   A3
  421.  
  422.    FUNCTION
  423.  
  424.         Pops up an Info-Requester with more or less detailed information
  425.         on the currently loaded Sample/Module.
  426.         A window pointer may be given to select the place to pop it up.
  427.  
  428.    INPUT(S)
  429.  
  430.         handle - a valid handle
  431.         window - a valid Window Pointer or NULL
  432.         future - always NULL yet
  433.  
  434.  
  435.    RESULT
  436.  
  437.         NULL or an adequate SPERR-Errorcode.
  438.  
  439.    SEE ALSO
  440.  
  441.         SPO_SetReqIOWindow()
  442.  
  443.  SPObject.library/SPO_CheckFileType         SPObject.library/SPO_CheckFileType
  444.  
  445.    NAME
  446.         SPO_CheckFileType  (V1)
  447.  
  448.    SYNOPSIS
  449.  
  450.         ULONG SPO_CheckFileType(BPTR filehandle, UBYTE *filename,
  451.         D0    -$66              A1                 A2
  452.  
  453.                                 struct SPOCheckFile *spo_check)
  454.                                 A3
  455.  
  456.    FUNCTION
  457.  
  458.         Checks, if the given file (or ClipBoard entry, or whatever)
  459.         fits to this SPObject and can be handled therein.
  460.  
  461.         Other media as SPO_MEDIUM_DISK requite spo_check to
  462.         be non-NULL and initialized.
  463.  
  464.         Be prepared, to handle NULL pointers to filename and handle.
  465.  
  466.    INPUT(S)
  467.  
  468.         handle    - a valid handle
  469.         name      - a valid AmigaDOS FileName
  470.         spo_check - a pointer to a SPOCheckFile structure or NULL
  471.                     for disk-access (default)
  472.  
  473.    RESULT
  474.  
  475.         NULL or an adequate SVERR-Errorcode.
  476.  
  477.    SEE ALSO
  478.  
  479.         -
  480.  
  481.  SPObject.library/SPO_SetReqIOWindow       SPObject.library/SPO_SetReqIOWindow
  482.  
  483.    NAME
  484.         SPO_SetReqIOWindow  (V1)
  485.  
  486.    SYNOPSIS
  487.  
  488.         ULONG SPO_SetReqIOWindow(APTR handle, struct Window *window)
  489.         D0    -$6c               A1           A2
  490.  
  491.    FUNCTION
  492.  
  493.         Sets a new Default-Window (default : IntuitionBase->FirstWindow)
  494.         for any Requester IO.
  495.  
  496.    INPUT(S)
  497.  
  498.         handle - a valid handle
  499.         window - a valid Window Pointer or NULL
  500.  
  501.    RESULT
  502.  
  503.         NULL or an adequate SPERR-Errorcode.
  504.  
  505.    SEE ALSO
  506.  
  507.         SPO_FileInfoReq
  508.  
  509.  SPObject.library/SPO_ContinueReplay       SPObject.library/SPO_ContinueReplay
  510.  
  511.    NAME
  512.         SPO_ContinueReplay  (V1)
  513.  
  514.    SYNOPSIS
  515.  
  516.         ULONG SPO_ContinueReplay(APTR handle)
  517.         D0    -$72               A1
  518.  
  519.    FUNCTION
  520.  
  521.         Some SPObjects support to continue a Sample/Module which
  522.         has been stopped by calling SPO_StopReplay().
  523.  
  524.    INPUT(S)
  525.  
  526.         handle - a valid handle
  527.  
  528.    RESULT
  529.  
  530.         NULL or an adequate SPERR-Errorcode.
  531.  
  532.    SEE ALSO
  533.  
  534.         SPO_SuperPlay(), SPO_StopReplay()
  535.  
  536.  SPObject.library/SPO_FastForward             SPObject.library/SPO_FastForward
  537.  
  538.    NAME
  539.         SPO_FastForward  (V1)
  540.  
  541.    SYNOPSIS
  542.  
  543.         ULONG SPO_FastForward(APTR handle)
  544.         D0    -$78            A1
  545.  
  546.    FUNCTION
  547.  
  548.         Some SPObjects might support a "cassette recorder"-like way
  549.         to browse trough a Sample/Module via FastForward and Rewind.
  550.  
  551.    INPUT(S)
  552.  
  553.         handle - a valid handle
  554.  
  555.    RESULT
  556.  
  557.         NULL or an adequate SPERR-Errorcode.
  558.  
  559.    SEE ALSO
  560.  
  561.         SPO_FastBackward()
  562.  
  563.  SPObject.library/SPO_FastBackward           SPObject.library/SPO_FastBackward
  564.  
  565.    NAME
  566.         SPO_FastBackward  (V1)
  567.  
  568.    SYNOPSIS
  569.  
  570.         ULONG SPO_FastBackward(APTR handle)
  571.         D0    -$7e            A1
  572.  
  573.    FUNCTION
  574.  
  575.         Some SPObjects might support a "cassette recorder"-like way
  576.         to browse trough a Sample/Module via FastForward and Rewind.
  577.  
  578.    INPUT(S)
  579.  
  580.         handle - a valid handle
  581.  
  582.    RESULT
  583.  
  584.         NULL or an adequate SPERR-Errorcode.
  585.  
  586.    SEE ALSO
  587.  
  588.         SPO_FastForward()
  589.  
  590.  SPObject.library/SPO_GetSampleBuffer     SPObject.library/SPO_GetSampleBuffer
  591.  
  592.    NAME
  593.         SPO_GetSampleBuffer  (V1)   *** OBSOLETE : Use SPO_GetSampleList()
  594.  
  595.    SYNOPSIS
  596.  
  597.         ULONG SPO_GetSampleBuffer(APTR handle, UBYTE **buffer,
  598.         D0    -$84                A1           A2
  599.  
  600.                                   ULONG *buffersize)
  601.                                   A3
  602.  
  603.    FUNCTION
  604.  
  605.         This function is OBSOLETE. Don't use it.
  606.  
  607.         Use SPO_GetSampleList() instead, which can handle more than one
  608.         Sample and also returns the information related to them.
  609.  
  610.    INPUT(S)
  611.  
  612.         handle     - a valid handle
  613.         buffer     - a pointer to a buffer pointer
  614.         buffersize - a pointer to a buffersize pointer
  615.  
  616.    RESULT
  617.  
  618.         NULL or an adequate SPERR-Errorcode.
  619.  
  620.    SEE ALSO
  621.  
  622.         SPO_GetSampleList()
  623.  
  624.  SPObject.library/SPO_GetSampleInfo         SPObject.library/SPO_GetSampleInfo
  625.  
  626.    NAME
  627.         SPO_GetSampleInfo  (V1)     *** OBSOLETE : Use SPO_GetSampleList()
  628.  
  629.    SYNOPSIS
  630.  
  631.         ULONG SPO_GetSampleInfo(APTR handle, ULONG *samplesPerSec,
  632.         D0    -$8a              A1           A2
  633.  
  634.                                 ULONG *volume, APTR future)
  635.                                 A3             D1
  636.  
  637.    FUNCTION
  638.  
  639.         This function is OBSOLETE. Don't use it.
  640.  
  641.         Use SPO_GetSampleList() instead, which can handle more than one
  642.         Sample and also returns the information related to them.
  643.  
  644.         This function only returns info on 8 Bit Samples.
  645.  
  646.    INPUT(S)
  647.  
  648.         handle        - a valid handle
  649.         samplesPerSec - a pointer to a buffer pointer
  650.         volume        - a pointer to a buffersize pointer
  651.         future        - always NULL yet
  652.  
  653.    RESULT
  654.  
  655.         NULL or an adequate SPERR-Errorcode.
  656.  
  657.    SEE ALSO
  658.  
  659.         SPO_GetSampleList()
  660.  
  661.  SPObject.library/SPO_GetSampleList         SPObject.library/SPO_GetSampleList
  662.  
  663.    NAME
  664.         SPO_GetSampleList  (V2)
  665.  
  666.    SYNOPSIS
  667.  
  668.         ULONG SPO_GetSampleList(APTR handle, struct SPO_SampleList **list)
  669.         D0    -$90              A1           A2
  670.  
  671.    FUNCTION
  672.  
  673.         While/after loading a Sample-File SPObjects might create
  674.         a special list of all Samples, which appear in the File.
  675.         This will usually be one one Sample for SampleFiles, but many more
  676.         for ModuleFiles.
  677.  
  678.         Not all SPObjects, especially not all ModuleType-SPObjects,
  679.         may support this and will return an error value or an empty list.
  680.  
  681.    INPUT(S)
  682.  
  683.         handle - a valid handle
  684.         list   - a pointer to a SPO_SampleList pointer
  685.  
  686.    RESULT
  687.  
  688.         NULL or an adequate SPERR-Errorcode.
  689.  
  690.    SEE ALSO
  691.  
  692.         SPO_SetSampleList()
  693.  
  694.  SPObject.library/SPO_SetSampleList         SPObject.library/SPO_SetSampleList
  695.  
  696.    NAME
  697.         SPO_SetSampleList  (V2)
  698.  
  699.    SYNOPSIS
  700.  
  701.         ULONG SPO_SetSampleList(APTR handle, struct SPO_SampleList *list)
  702.         D0    -$96              A1           A2
  703.  
  704.    FUNCTION
  705.  
  706.         For saving Sample-Files with, there may be used
  707.         a special list of all Samples, which should appear in the File.
  708.  
  709.         This will usually be one one Sample for SampleFiles, but many more
  710.         for ModuleFiles.
  711.  
  712.         Not all SPObjects, especially not all ModuleType-SPObjects,
  713.         may support this and will return SPERR_ACTION_NOT_SUPPORTED.
  714.  
  715.    INPUT(S)
  716.  
  717.         handle - a valid handle
  718.         list   - a pointer to a SPO_SampleList
  719.  
  720.    RESULT
  721.  
  722.         NULL or an adequate SPERR-Errorcode.
  723.  
  724.    SEE ALSO
  725.  
  726.         SPO_GetSampleList()
  727.  
  728.